Skip to main content

Client Event Webhooks Documentation

Overview​

Client event webhooks enable external systems to receive real-time notifications about events occurring within FNZ's ecosystem. These webhooks eliminate the need for constant polling and ensure external systems stay updated seamlessly with events such as payment status changes, transaction updates, and system alerts.

How Client Webhooks Work​

1. Event Triggering​

Webhooks are triggered by predefined events within the FNZ system. Examples include:

  • Payment Status Updates: Notifications for changes in payment status, e.g., "COMPLETED," "FAILED," or "PENDING."
  • Transaction Events: Notifications for new transactions, refunds, or adjustments.
  • System Notifications: Alerts for system updates, maintenance, or errors.

2. Webhook Delivery​

Once an event is triggered:

  • FNZ sends a POST request to the client’s specified endpoint.
  • The payload contains event-specific details in a JSON format.

Webhook Structure​

HTTP Request Details​

  • Method: POST
  • Headers:
    • Content-Type: application/json
    • X-FNZ-Event: Specifies the type of event (e.g., PAYMENT_STATUS_CHANGED).
    • X-FNZ-Signature: HMAC-SHA256 signature for payload validation.
  • Body: Contains the event details in JSON format.

Sample JSON Payload​

{  
  "event": "PAYMENT_STATUS_CHANGED",  
  "timestamp": "2024-11-18T08:00:00Z",  
  "clientId": "client_123",  
  "details": {  
    "paymentId": "98765",  
    "status": "COMPLETED",  
    "amount": 500.00,  
    "currency": "USD"  
  }  
}

Security Measures​

To ensure secure and reliable webhook delivery, FNZ implements the following security protocols:

  • IP Whitelisting: Webhooks are only sent to endpoints that are registered and whitelisted by the client.
  • Payload Signing: The X-FNZ-Signature header contains an HMAC-SHA256 signature of the payload. Clients must validate this signature using a shared secret key to verify authenticity and integrity.
  • HTTPS Requirement: Webhook requests must be sent over HTTPS to encrypt data during transmission.
  • Retry Mechanism: FNZ retries webhook delivery in case of failures, following an exponential backoff strategy.

Setting Up Client Webhooks​

Endpoint Registration​

Clients must provide a secure HTTPS endpoint where they want to receive webhook notifications.

Security Configuration​

  • Share a secret key with FNZ for validating webhook signatures.
  • Provide a list of trusted IP addresses for whitelisting.

Testing Environment​

FNZ offers a sandbox environment for testing webhook reception and signature validation before production deployment.

Error Handling and Responses​

Response Expectations​

  • 200 OK: Indicates successful processing of the webhook.
  • 4xx or 5xx: Indicates an error. FNZ will retry the webhook delivery.

Retry Policy​

  • FNZ retries failed webhook deliveries for up to 24 hours, using exponential backoff intervals.
  • Persistent failures will trigger alternative notifications, such as email alerts or system messages to the client.